home
***
CD-ROM
|
disk
|
FTP
|
other
***
search
/
Tech Arsenal 1
/
Tech Arsenal (Arsenal Computer).ISO
/
tek-11
/
grumptem.zip
/
GENGRUMP.DOC
< prev
next >
Wrap
Text File
|
1993-01-04
|
21KB
|
476 lines
GENGRUMP TEMPLATE
----------------
The only difference between this template and General.tem is that it has
hooks in it for calling the Grumpfish Popup routines and the Grumphelp
library. The grumpfish modifications will only work if you are generating
Clipper Summer 87 code. If you say yes to generate Grumpfish stuff and you
have flavor set to anything else, it gives you a message saying that you
can't do it. It will generate anything general.tem will.
If you want to standarize on this, you can rename this file to general.tem
and renam stdgrump.tlb to stdfuns.tlb and do a global search and replace in
this template for stdgrump and replace it with stdfuns
I hope you find this little modification usefull. All of the credit should
however go to Greg Lief of Grumpfish, Inc. for providing us with his
wonderful Grumpfish Libraries in the first place.
Introduction
------------
Summary
-------
This template is intended to be a "single-stop" for most program
generation.
Features
--------
GENERAL can generate:
* Help screens,
* Menus,
* Edit screens,
* Add screens,
* Delete screens,
* Browse screens,
* Search screens,
* Any combination of the above,
* All of the above (except menus) with multiple pages.
* All of the above with popup menus.
Structure of Generated Code.
Mostly, GENERAL structures the generated code into a main part
and ancilliary procedures to support the main functions.
GENERAL can structure the code as:
* a single, stand-alone program,
* as a single sub-program file,
* a PRG file with the ancilliary part in a separate procedure file,
* the whole in the form of procedures in a procedure file.
* In all cases where generation is to a procedure file, the
new code may be optionally appended to an existing
procedure file.
GENERAL allows:
* Multi-user code with record locking only on file updates,
* Multi-user code with "safety" record locking when a record
is accessed for editing.
* The main record locking function can be shared with other
parts of the system and is generated upon your request.
* Embedded READ's by optionally simulating a single READ
statement with a separate READ statement for each @..GET.
Templates Obsoleted by GENERAL
------------------------------
GENERAL replaces the following templates on the version 1.00 diskettes:
BASIC.TEM
BASIC@P.TEM
DOAPPEND.TEM
DOEDIT.TEM
MAINMEN.TEM
MAINMN@P.TEM
MPAPPEND.TEM
MPBAS.TEM
MPBAS@P.TEM
MPEDIT.TEM
POPMEN3P.TEM
POPMENS.TEM
Examples
--------
WALLCUST.WW
Straightforward data screen with menu. If you want to see
this example with a popup menu, take the cursor to the menu
box, type Ctrl-PgDn and type 'P' to toggle the popup-flag.
WALLMP.WW
Multi-page data screen with popup-menu. When you run the
generated programm you can type PgUp/PgDn at any point to
switch pages.
WALLMP2.WW
Similar to WALLMP but has a shorter menu overlapping the
data display pages.
WALLMENU.WW
A pure menu with no data fields.
WALLPOPM.WW
A pure pop-up/pop-down menu.
To see this in action, load WALLCUST.WW, go to the "GOTO"
option, use F7:MENU and revise its definition. Replace the
action code with:
DO UPS
Change the trigger character to "U" and, after exiting the
F7:Menu, change the prompt to "UPS". Generate as a main
program with procedures in the same file. Now load
WALLPOPM.WW and generate. When it asks you to confirm the
name, enter any false name. When GENERAL asks if you want a
main program generated, answer "No". Answer "Yes" to
generating into a procedure file. When GENERAL asks you for
a file, give it the same name as you gave when you generated
from WALLCUST, then specify that you want code to be appended
to this file. That's important, otherwise you'll lose the
code generated from WALLCUST. When you're asked for the name
of the main procedure, enter "UPS". You've now created a
small system using two separate pieces.
Program Linkages
----------------
GENERAL's generality is designed to allow you to generate a system
gradually, in small pieces. The entire system can be pieced
together using the menus generated by GENERAL. Validation functions
can also be used for linkages to verification functions.
Validation functions may do lookups on DBF's and can even perform
editing or record adding to DBF's.
How to use GENERAL
------------------
Summary.
-------
GENERAL's objective is to decide what to do as much as possible
from the form design. For instance, if GENERAL finds no fields
in the form it assumes you want to generate either a pure menu or
a text-display screen (such as a help screen). If it finds both
fields and menu options on the screen, it assumes you want a
multi-function data screen.
Menus.
-----
GENERAL's simplest task is to generate a text-display module.
All you need do is draw your boxes, arrows, text, etc. and
generate. The next simplest generation is that of a pure menu.
Design your form with just a menu and no fields. If GENERAL
finds that it can use special language features to generate your
menu, it will use them. For example, when generating for Clipper
or Fox+, if all your menu options are only one line high, GENERAL
will generate @..PROMPT code. Likewise, in dBASE IV generation,
GENERAL would use ON SELECTION PAD code provided no option
(except the QUIT option) had more than a single action.
Menu Actions
------------
There are two types of actions that you can specify in the action
code for a menu option: straight Dbase code or special keywords
recognized by GENERAL.
The most important keyword is QUITMENU. This tells GENERAL which
option quits the menu and allows GENERAL to generate appropriate
code to exit the menu. Always insert the QUITMENU keyword as the
last action in the quit menu option. For dBASE IV users, the
QUITMENU keyword has the added advantage that in the QUITMENU option
only, you can specify more than one action and GENERAL will still
generate the more compact ON SELECTION PAD code provided all other
options have only one action and all option prompts are only one
line high.
One example of code you might want to insert with the QUIT option is:
SET COLOR TO W/N && Reset color on exit to white on black
CLEAR && Clear screen in this color
QUITMENU
If you combine a menu with a data screen (a screen containing
fields), GENERAL will assume that some menu options control actions
on the data screen. In this case, GENERAL will check for other
keywords which stand for actions you want to perform on your data
screen. These are: EDIT, ADD, NEXT, PREVIOUS, FIRST, LAST, JUMP,
ERASE, and SEARCH. These keywords are converted by GENERAL to the
appropriate Dbase code to perform these functions on your data
screen.
The meanings of the keywords are:
EDIT -- edit current record(s)
ADD -- append a new record to the active file(s)
NEXT -- Skip forward to next record on the primary DBF
and display new values.
PREVIOUS -- Skip back one record on the primary DBF and
display new values.
FIRST -- Skip to beginning of the primary DBF and display
values.
LAST -- Skip to last record on the primary DBF and display
values.
JUMP -- Go to specific record number and display values.
SEARCH -- Prompt for the value of a key to search on the
main index file of the primary DBF and display
all values if found, else restore prior record.
Menu Restrictions:
All options in your form must appear either in a single box or in no
box. That is, if any option appears outside all boxes, then so must
all the others. Likewise, if any option appears inside a box, then
so must all the others. If, for any reason, you want extraneous
options in your form, then enclose the options for GENERAL to
process within a box called "MENU". If you do that, then GENERAL
will ignore all other options outside the "MENU" box.
Note for dBASE IV Users.
GENERAL will use the the dBASE IV menu commands if it thinks that
they are appropriate. That is, if all the menu prompts are only
one line high and no option has more than one action except possibly
the QUITMENU option. However, version 1.0 of dBASE IV does not
handle certain menu processes correctly. If you have any trouble
with dBASE IV menus, then you should request GENERAL to produce
generic menu code by placing the keyword "NOPADS" in any slot
of the menu box.
Popup Menus
-----------
If your menu options are entirely contained inside a popup box, then
when the user chooses the Edit, Add, or Search options, the menu
disappears and reappears when editing is completed.
If you are generating a pure menu which you have designated as a
popup then GENERAL will create code to restore the prior screen on
quitting the menu.
Data Screens
------------
If your form has no menu options, then GENERAL assumes that you have
a single-purpose data screen and asks you what that function is.
Your choices are:
E - Edit, A - Add, D - Delete, S - Search.
The module will be generated without a menu and when called, the
module will immediately go into the function you chose. The user
can exit the module in the usual way -- by typing ^W or ^End to
save, or Esc to abandon.
As explained above, if your screen has both a menu and a data
screen, GENERAL will search your options for the special keywords
which control actions on the data screen. You can include other
actions if you wish; these must be inserted as Dbase code. You can
mix Dbase code and GENERAL's keywords in the same option provided
that GENERAL's keywords appear on their own option-action line.
Multi-Page Data Screens.
-----------------------
Sometimes, a database has too many fields to fit on a single screen.
GENERAL can generate code for several pages of overlapping data
boxes. These boxes are called "pages". The pages may be arranged
any way you want. The pages must be numbered. Each page box must
have the keyword "page" in a general slot followed by a page number.
No two boxes can have the same number and you are limited to a
maximum page number of 10.
Suppose you require three overlapping boxes to display all the
relevant fields in an application. In any slot of the three boxes,
insert the word PAGE followed by the page number for that box. So
in the first box, you would insert the text "PAGE 1" in one of its
slots, in the second box, "PAGE 2", and in the third, "PAGE 3".
Regardless of how you number the pages, the topmost page will be
the first displayed.
The end user can flip from one page to another with the PgDn and
PgUp keys. These are available to the user at all times until the
module is exited. Only data in the currently topmost page is
displayed. So, for example, if page 2 is currently the top page
then the values in the fields in the other boxes (boxes 1 and 3 in
our example) are not displayed.
Adding a new procedure to an existing program file.
--------------------------------------------------
Using GENERAL, you can build systems gradually, in small pieces.
One way of doing this is to add procedures to an existing file
rather than making a new PRG file for every new module.
Unfortunately, to add to an existing file you need to lie to UI.
But it's a necessary lie. When you start generation, UI displays a
file for you to confirm as the output file. At this point, UI has
not fired up GENERAL and so UI is unaware that you might want to
append to an existing file. So, at this point, enter a nonsense
file name. UI will create this file and you can later delete it.
For instance, I enter a file name of X and when I'm done for the day
I delete X.PRG.
GENERAL now gets control and asks you if you are generating a main
program. You answer "No". GENERAL then asks if you want to
generate into a procedure file. Answer "Yes". GENERAL will prompt
you for the name of the procedure file. Now you can enter the real
name of the file, the file you want to append to. GENERAL checks
that this file exists and if it does, asks you if you want to append
to it. Of course, you answer "Yes". Finally, GENERAL asks you what
name to give your main procedure. It wants the name by which your
procedure will be called from outside this module.
Sample Dialog.
Here is an example of the dialog:
UI:
Output file: D:\UI\PRG\MYFORM.PRG
You cancel this by typing,
Output file: X (X.PRG is a file you later delete.)
GENERAL:
Are you generating a main program (the first called)?
You: N (No)
GENERAL:
Do you want this module generated into a procedure file?"
You: Y (Yes)
GENERAL:
Name of procedure file:
You: MAINPROC (Name of existing PRG file)
GENERAL:
File exists. Append to it?"
You: Y (Yes)
GENERAL:
Name of main procedure:
You: BROWSE (Name by which your procedure
is to be called)
Multi-User Record Locking.
-------------------------
If you go to UI's F10:Config menu and select the Generation
option. You will see an option called: "generate Multi-user
code?". If you set this option to YES then GENERAL will assume
you want record locking.
GENERAL will generate record-locking code for all DBF's that are
about to be changed. GENERAL, at your option, will generate the
record-locking test function called LOCK_TEST. If you have already
generated part of your system and requested generation of the
LOCK_TEST function, then you should decline to generate it again
unless you are forced to do so to avoid SET PROCEDURE conflicts.
(Clipper users may need multiple copies of LOCK_TEST in order to
overcome overlay conflicts.)
Two Forms of Record Locking.
Two forms of record locking can be generated by GENERAL. The
simplest is the lock during the actual update only. The other is
record locking during an entire editing session. The second is
safer than the first but is more liable to cause record freezing.
The LOCK_TEST function has a timeout and will interrogate the user
regarding what action to take in the event of a timeout. There
follows two examples of record-locking with the different record-
locking options.
Example with Simple Locking.
Let's assume that there are two users, called A and B, on different
computers on the same network, both working on the same DBF file.
The DBF file contains several fields of which two are: LASTNAME
(character) and AMOUNT (numeric, dollars). In our first example,
the two users are both running the same application which locks
records only for the actual record update.
User A starts editing record 12, user B starts editing record 8.
Neither user is hindered since they are editing different records.
All is normal. Now suppose they both start editing record 8
simultaneously. So far there is still no hindrance since editing
begins by reading the existing data in record 8 and there is no
locking on record access, only on record update. At this moment,
before either user has started editing, they are both looking at
exactly the same information. Suppose user A just wishes to change
LASTNAME from "Jones" to "Smith". He finishes ahead of user B, and
types Ctrl-W to save his screen. Since both applications have
record locking only on update, the record update proceeds normally
because user B is still editing. Meanwhile, user B has to change
AMOUNT from $100 to $1,000. She finishes and saves the screen with
Ctrl-W. This also proceeds normally. Unfortunately, user A's
modification has been lost. The record again contains "Jones" in
the LASTNAME field because that is what it contained when user B
accessed the record and therefore that is what is contained when
user B saves the record as user B did not change that field.
Example with Safety Locking.
User A and user B are again running the same application, but this
time the application has record locking specified for entire editing
sessions. Now see what happens in the above situation. User A is
the first to start editing record 8 and succeeds in retrieving the
current record since no one else is editing as yet. User B now
tries to edit record 8, but cannot because the attempt to lock the
record at the beginning of the edit session fails since A already
has the record locked. Consequently, the above situation where user
A lost changes cannot occur.
Calculated Fields.
-----------------
GENERAL assumes that all calculated fields are to be calculated
after data entry but before record update.
Whenever a screen contains calculated fields, GENERAL will generate
code to redisplay the screen after all data has been entered. If
the application has a menu, there is no confirmation required. The
edited record is still on the screen after the operator finishes
editing. If there was an error, the operator can resume editing
immediately. If the application consists of a single function, with
no menu, then confirmation is required after viewing the calculated
fields.
Validation Functions
--------------------
You can enter validation functions in the Valid Slot in any field.
If you do, GENERAL will insert your function in the VALID clause on
that field. There is no restriction on what the validation function
may do. In particular, you may insert a data entry screen in the
validation. For instance, if during a lookup, the user does not
find a desired record, you might allow the user to add a new record
at that point.
Embedded READ's.
However, if you do want data entry in the validation, you must
answer "yes" to GENERAL's question: "Do any of your validation
routines use @..GET and READ?" This will cause GENERAL to insert
a READ after every @..GET statement together with appropriate
code to control the cursor.
Generation modes.
----------------
You can suppress all of GENERAL's questions (though they are few) by
creating a box called PARAM which contains all your parameters.
Alternatively, you can place the answers in the slots of a box with
the word PARAM in slot1. GENERAL will recognize the following in the
slots 1 to 5 of the parameter box:
MAIN Generate a main (top-level) program.
MODULE Generate a sub-PRG.
PROCFILE <file> Generate a procedure file.
PROCNAME <name> Name of top-level procedure (only if
PROCFILE is also specified.)
SUBPROCS <file> Generate separate procedure file for
supporting procedures. (Valid only if
PROCFILE was NOT specified.)
APPEND (Only with SUBPROCS) Append to SUBPROCS
file. (Otherwise, GENERAL will overwrite
any existing file.)
EMBEDDED Allow usage of @..GET's and READ in
validation functions.
SCREEN LOCK Only for multiuser applications: Lock
SAFETY LOCK entire edit sessions.
UPDATE LOCK Only for multiuser applications: Lock
on record update.
GENPROC Generate the LOCK_TEST function.
Future Enhancements
-------------------
Scrolling lookups will be available in the LOOKUP.TEM file and
these can be linked in very easily to GENERAL-generated code.
Detail record screens.
Screens which can show and allow editing and adding of
several records.
Searches using the Dbase LOCATE command.
Popup data screens.
Popup simulation for dBASE III and QuickSilver.
D